home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / pascal / tpp112.zip / TPP.DOC < prev    next >
Text File  |  1992-04-18  |  19KB  |  445 lines
  1. ----------------------------------------------------------------------
  2. 04/18/92        Turbo Pascal Pre-Processor         All Rights Reserved
  3. Copyright (c) 1991-1992 by SupremeSoft                Version 1.12
  4. ----------------------------------------------------------------------
  5.  
  6. Introduction
  7. ------------
  8.  
  9. What is TPP? TPP is a pre-processor designed to work with Turbo Pascal. 
  10. Many programmer's who are both C and Pascal programmers find that they 
  11. miss C's pre-processing capabilities. 
  12.  
  13. In addition, professional Pascal programmers find it quite absurd to 
  14. declare constants for such mundane things as maximum values for array 
  15. indexes. This adds to the programs code size, as well as wasting precious 
  16. memory. Why declare a constant when you'll only be using it as a fixed 
  17. value, which the compiler can determine at compile-time as it is?
  18. In C, all you need to do is use the pre-processor to define this
  19. value. (The question of why use constants at all comes up. Especially if 
  20. they are useful, but wasteful of resources. Most languages use constants, 
  21. whereas C and C++ provide macro equivalents, and thus have no constant 
  22. keywords) 
  23.  
  24. Finally, Turbo Pascal has a gotcha for all constants. They sit in your 
  25. data segment. Turbo Pascal, though smart in some ways, is not smart 
  26. enough to know that this constant is only a "hard coded" value, and will 
  27. thus not replace all references for that constant with its definition.
  28. Besides this, there is a big caveat for using constants as initializers.
  29. Reading your Turbo Pascal manual carefully, you will see that any constant
  30. is only initialized ONCE. Even if it is declared in a procedure, it is only
  31. initialized ONCE, and lives in the data segment and NOT the procedures local
  32. call stack!
  33.  
  34. In comes TPP. TPP will take your simple constants and replace all 
  35. occurrences of that constant with its definition. Besides that, TPP can 
  36. be used to abbreviate coding declarations which will later be expanded at 
  37. compile time. 
  38.  
  39. -----------------
  40. How to use TPP
  41. -----------------
  42.  
  43. TPP was designed to allow you to use the same source code that you would 
  44. normally use, but also allow you to use TPP keywords. In addition, TPP 
  45. works exactly like the Turbo Pascal Compiler. It will not recompile units 
  46. that do not need to be. (Although, it is not as smart as the Turbo 
  47. compiler as you will see later) 
  48.  
  49. TPP scans your source, looking for a {#DEFINE} statement. This is the 
  50. signal to TPP that a macro definition is about to start. After this comes 
  51. the regular constant definition. For example: 
  52.  
  53.   Normal source:    Const
  54.                         UpperLimit = 3;   {This is the upper limit}
  55.                         LowerLimit = -1;  {This is the lower limit}
  56.  
  57.  
  58.   To adapt to TPP:  Const
  59.                       {#DEFINE} UpperLimit = 3;   {This is the upper limit}
  60.                       {#DEFINE} LowerLimit = -1;  {This is the lower limit}
  61.                                  
  62. Using this {#DEFINE} statement, your source will compile under Turbo as
  63. usual, but can also be compiled using TPP. You do not need to keep two
  64. different sets of source code.
  65.  
  66. That is all there is to it. Now, every occurrence of UpperLimit will be 
  67. replaced by a "3". You can also define string constants etc. In short any 
  68. constant that will work for the Turbo compiler will work for TPP. 
  69.  
  70. Initialized constants, will *NOT* work in TPP, and should be avoided 
  71. during regular use of the Turbo compiler. Initialized constants have 
  72. numerous flaws and many, many gotchas. (Contact us for more detailed 
  73. information on why not to use initialized constants) For example, the 
  74. following is *NOT* legal for TPP: 
  75.  
  76.         Const
  77.           {#Define} LowerLimit : Byte  = -1;  {This is the lower limit}
  78.                   
  79.  
  80. You may use TPP to ease your coding a bit, by using the TPP macro feature 
  81. as you would normal text macros. For instance: 
  82.  
  83.       {#DEFINE} DOS =  Intr(21h);
  84.  
  85. Then, in your code, you may say:  DOS;  {Call DOS} 
  86. and TPP will change this to    :  Intr(21h);  {Call DOS} 
  87.  
  88. Note that TPP can thus be used for other things than just constants!
  89. {#DEFINE} statements may be used anywhere in your source code.
  90.  
  91. And of course, TPP is not case sensitive.
  92.  
  93. -------------
  94. Limitations
  95. -------------
  96.  
  97.  
  98. TPP is not like the C macro pre-processor. You may not pass variables in 
  99. or out, nor do arithmetic expressions. For example, the following are 
  100. accepted, but are probably not what you want the macro to do:
  101.  
  102.    1.    {#DEFINE} TWICE(X) = X*X;
  103.    2.    {#DEFINE} HIGH(X) = Odd(X) < Even (X);
  104.    3.    {#DEFINE} Limits = 32 * MaxValue;
  105.                      
  106. For definition 1, you would need to have a statement of: TWICE(Z);
  107. Expansion then becomes: X*X;
  108. You probably want: Z*Z;
  109.  
  110. For definition 2, you would need to have a statement of: HIGH(Z);
  111. Expansion then becomes: Odd(X) < Even(X);
  112. You probably want: Odd(Z) < Even(Z);
  113.  
  114. For definition 3, you would need to have a statement of: Limits;
  115. Expansion then becomes: 32 * MaxValue;
  116. Note:  This is not evaluated at macro definition time, unlike in C.
  117.        However, Turbo will usually evaluate it at compile-time, so this
  118.        is actually a GOOD use for TPP.
  119.  
  120. You must be careful not to have the macro name anywhere else 
  121. in your source code, or else it will get expanded. (That is rather 
  122. obvious)
  123.  
  124.  
  125. If you use the Const feature of TPP, be careful of the following:
  126.  
  127.        Const
  128.          {#DEFINE} UpperLimit = 3;   {This is the upper limit}
  129.          {#DEFINE} LowerLimit = -1;  {This is the lower limit}
  130.  
  131.        Type 
  132.              .
  133.              .
  134.           
  135.                       
  136. When TPP processes your file, everything but the comments will be 
  137. stripped out, leaving: 
  138.  
  139.        Const
  140.            {This is the upper limit}
  141.            {This is the lower limit}
  142.  
  143.        Type 
  144.              .
  145.              .
  146.  
  147. The Turbo compiler, will *NOT* accept this. There must be something 
  148. following the CONST declaration. Be aware of this problem. The only real 
  149. work around is to comment out the CONST statement. (This may changed
  150. in later versions of TPP)
  151.  
  152. -------------
  153. How TPP works
  154. --------------
  155.  
  156.  
  157. TPP will scan your source file looking for {#DEFINE} statements or macro 
  158. names. It handles Units just like the Turbo compiler, and looks for a 
  159. USES keyword. If it finds one, it suspends processing of the current file 
  160. and looks at the last file in the USES list. (Just as the Turbo compiler 
  161. does) If the TPU for that file is older than the file, TPP will process 
  162. that file. This is done for all Units in the USES list. 
  163.  
  164. You may define a macro in one unit, and use it in another, as long as 
  165. that unit is listed in the second file's USES list. Confused? Follow the 
  166. same programming style as you do regularly. TPP needs no change in 
  167. programming! It will allow you to treat your source the same way as Turbo 
  168. does. Consider the following:
  169.  
  170. Unit 1;
  171.  ...
  172. {Not the next line can be in either the interface OR the implementation
  173.  section. Either way it will be visible to other units using this unit}
  174.  
  175.  {#DEFINE} Upper = 99;
  176.  
  177. Unit 2;
  178.  
  179.  Uses Unit 1;
  180.  
  181. ...
  182.  
  183. Var t : array[1..Upper] of real;
  184.  
  185.  
  186. Even though Unit2 doesn't declare Upper, it can still use it.
  187. ------------------------------------------------------------------
  188. One major flaw in TPP:
  189.    If Unit1 does NOT need re-compiling, then the macro Upper will never
  190.    get defined for TPP!
  191. -------------------------------------------------------------------
  192.  
  193. Once TPP encounters a macro, it stores the macro name, and its 
  194. corresponding definition. In all later files, any time the macro name is
  195. detected, it will get replaced with the definition. Once TPP reads the 
  196. macro, it will remove it from the source file. Thus causing the Turbo 
  197. compiler to "ignore" the macro, since it isn't there. 
  198.                                            
  199. TPP will scan all the files needed, but will only produce a new file if 
  200. any changes are made to the original source. Depending on the mode of 
  201. operation, this new file will either overwrite the original source file, 
  202. be named DUM?.PAS or wil